pi-openui 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.1 (2026-10-30)
+
+- The README now renders on pi.dev and npm: screenshots are markdown images (pi.dev drops raw HTML tables and images) and
+  links to the documentation are absolute (pi.dev rewrote the relative ones to a CDN copy of the package, which has no `docs/`).
+  Nothing changes in the extension.
+
+## 0.1.0 (2026-10-30)
+
+- **Notes.** Pin a comment to a table cell, node, slice, point or paragraph; the notes go into pi's message box as one numbered
+  message, never straight to the agent. `/openui-notes`, a `[ notes ]` chip under every widget that has something to note, pins
+  and a tray. Mouse and keyboard (Tab to `[ Add ... ]`, or Down from a note, then Enter). Words from the widget are cleaned
+  before they reach the message. See docs/interaction.md.
+- **Pictures in Markdown.** A line that is only `![alt](path "caption")` draws a picture, in Markdown and in FAQ answers, through
+  the same code as `Image`. A missing file or a web URL is an error the assistant is told about.
+- **Size limits** for every list and string, as validation errors with the number in them, listed in the model's reference and in
+  docs/components/README.md. `compile()` can no longer throw. At most 12 pictures per widget.
+- **Cheaper to draw.** An unchanged widget costs nothing per frame (it was 8 ms for 17 widgets); layouts are kept per width;
+  terminal cells are shared and frozen (300 widgets: 47 MB down to 17 MB); wire routing shares a work budget (a 120-node
+  infrastructure map no longer freezes pi for 5 s); the picture cache is bounded by bytes; session state is dropped at shutdown.
+- The last column of every line is left empty, because pi's scrollbar is painted over it. It cut the `]` off the notes chip.
+- MIT license.
+- Installable with `pi install git:...`: a `pi` manifest and peer dependencies in `package.json`. See docs/releasing.md.
+- Fixed: an armed widget kept Enter after "Add to message", so the Enter meant to send the message would have pressed a widget
+  element.
+
+### First version
+
+- `render_widget` tool and the commands `/openui-gallery`, `/openui-file` and `/openui-focus`.
+- 23 components: Stack, Text, Card, Callout, Metric, Table, Tabs, Button, Choice, Faq, Markdown, CodeBlock, Image, BarChart,
+  LineChart, AreaChart, PieChart, RadarChart, GeoMap, Dag, Erd, InfraMap, SequenceDiagram, plus Tooltip.
+- Mouse and keyboard interaction, a hover bubble, tooltip panels, a copy button, sideways scrolling for wide diagrams.
+- Tooltips on Dag, Erd, InfraMap, SequenceDiagram, Table, Metric, BarChart, LineChart, AreaChart, PieChart, RadarChart, GeoMap
+  and Image, marked with a `◆`. A target that matches nothing is a validation error that lists the valid ones.
+- Pictures through pi-tui's image support (Kitty protocol), framed, with tooltips and a labelled fallback.
+- ERD relation ends are one cell each: `├ ┤ ┬ ┴` for one and `< > Λ V` for many.
+- Every glyph is audited against JetBrains Mono Nerd Font Mono.
+- Generated component pages with screenshots (`docs/components/`), checked by the tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Dai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# pi-openui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interactive dashboards, charts, diagrams and maps in the terminal, for the [pi](https://github.com/earendil-works/pi)
+coding agent. The agent writes a few lines of OpenUI Lang. pi draws a widget you can click or drive with the keyboard.
+
+It uses unicode characters, and real pictures where the terminal can show them. There is no browser, no HTML, no runtime
+dependency and no network access.
+
+![Dashboards, diagrams with tooltips, an infrastructure map, a picture in a frame, and notes pinned on a table and on a graph](https://raw.githubusercontent.com/newtonapple/pi-openui/main/docs/screenshots/hero.png)
+
+*Screenshots are drawn by `npm run screenshots` from the widget's real output, with pi's dark theme and JetBrains Mono.*
+
+## What you get
+
+- **One tool, `render_widget`.** The agent calls it with OpenUI Lang. Mistakes come back as a list of errors with line
+  numbers, so it fixes them and tries again. After a successful draw it says one short sentence.
+- **23 components.** Layout and text, metric tiles, tables, tabs, buttons and choices, FAQ, markdown, code with
+  highlighting and a copy button, images, bar, line, area, pie and radar charts, a world map, and four diagram types
+  (DAG, ER, infrastructure map, sequence). See the [component gallery](https://github.com/newtonapple/pi-openui/blob/main/docs/components/README.md).
+- **Interaction.** Click, or use Tab, the arrow keys, Enter and Esc. A button or a choice sends text to the agent as your next
+  message. See [docs/interaction.md](https://github.com/newtonapple/pi-openui/blob/main/docs/interaction.md).
+- **Notes.** Pin a comment to a table cell, a graph node or a pie slice, then send all of them to the agent as one numbered
+  message. You read and edit the message before it goes. See [Notes](#notes).
+- **Tooltips.** An element with a tooltip shows a small `◆`. Hover for a hint bubble, click or press Enter for a panel with
+  detail, code and a link. See [Tooltip](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Tooltip.md).
+- **Pictures.** An `Image` draws the real picture in terminals that speak the Kitty graphics protocol, inside a frame that
+  can carry a tooltip. A line of Markdown that is only a picture, `![alt](path "caption")`, is drawn the same way, so a
+  README-style view is one `Markdown`. See [Image](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Image.md) and [Markdown](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Markdown.md).
+- **Robust diagrams.** Every graph, schema and map is routed on a character grid with one wire per edge. The tests decode
+  the finished picture back into its edges and compare them with the input. See [docs/diagrams.md](https://github.com/newtonapple/pi-openui/blob/main/docs/diagrams.md).
+
+## Install
+
+```sh
+pi install npm:pi-openui
+```
+
+That is all. There is nothing to build, and no dependencies to fetch: pi supplies the packages the extension imports. Start pi
+and run `/openui-gallery`. It needs pi 1.4 or newer.
+
+| What | Command |
+|---|---|
+| Install from npm | `pi install npm:pi-openui` |
+| Install one version | `pi install npm:pi-openui@0.1.0` |
+| Install from GitHub instead | `pi install git:github.com/newtonapple/pi-openui` (add `@v0.1.0` to pin a tag) |
+| Try it for one session | `pi -e npm:pi-openui` |
+| Install from a clone | `pi install /path/to/pi-openui` |
+| See what is installed | `pi list` |
+| Update | `pi update --extensions` |
+| Remove | `pi remove npm:pi-openui` |
+
+It is in pi's [package catalog](https://pi.dev/packages), which lists npm packages that carry the `pi-package` keyword. After an
+update pi shows this package's [changelog](CHANGELOG.md). Maintainers: see [docs/releasing.md](https://github.com/newtonapple/pi-openui/blob/main/docs/releasing.md).
+
+## Use it
+
+| What | How |
+|---|---|
+| Let the agent draw | Ask for a dashboard, a chart, a diagram, a table. It calls `render_widget`. |
+| One example of every component | `/openui-gallery`, or one kind: `/openui-gallery dag`, `erd`, `infra`, `sequence`, `geo`, `pie`, `line`, `image`, `table`, `tabs`, `markdown` |
+| Draw a file | `/openui-file path/to/widget.oui` |
+| Use the keyboard without the mouse | `/openui-focus` |
+| Write notes on a widget | Click `[ notes ]` under it, or `/openui-notes` |
+
+Gallery clicks are echoed locally and cost nothing. In a widget the agent drew, a Button or Choice click is sent to the
+agent as your next message.
+
+The mouse needs pi's default fullscreen mode. Everything also works from the keyboard.
+
+## Notes
+
+Pin a comment to one part of a widget, then send all your comments to the agent as a single message. Use it to say "this row
+is wrong" or "explain this node" without describing where it is.
+
+![A note pinned on a graph node, with the tray under the graph](https://raw.githubusercontent.com/newtonapple/pi-openui/main/docs/screenshots/notes-dag.png)
+
+1. Click `[ notes ]` under a widget, or run `/openui-notes`.
+2. Click a cell, node, slice or paragraph, or Tab to it and press Enter. pi's own editor opens. Type, press Enter.
+3. Click `[ Add 2 notes to your message ]`, or Tab to it and press Enter. The notes land in pi's message box as a numbered list.
+4. Read it, edit it, press Enter. Nothing is sent before that.
+
+Each note names its target the way the agent wrote it, for example `tbl` (Table) > row 3, column `State`, so the agent can find
+the line in its own source and answer by number. Words that come from the widget are cleaned before they reach your message,
+so a widget cannot slip an `@file` reference or a code span into something you are about to send.
+
+A widget holds 20 notes. They live in memory and are gone when the session ends. Keys, what each component lets you pick, and
+the details are in [docs/interaction.md](https://github.com/newtonapple/pi-openui/blob/main/docs/interaction.md#notes).
+
+## Components
+
+![Eight of the components: Table, LineChart, PieChart, GeoMap, Erd, SequenceDiagram, CodeBlock, RadarChart](https://raw.githubusercontent.com/newtonapple/pi-openui/main/docs/screenshots/components.png)
+
+All 23, with signatures, every argument, a checked example and tips: **[docs/components/](https://github.com/newtonapple/pi-openui/blob/main/docs/components/README.md)**.
+
+| Group | Components |
+|---|---|
+| Layout and text | [Stack](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Stack.md), [Text](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Text.md), [Card](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Card.md), [Callout](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Callout.md) |
+| Data | [Metric](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Metric.md), [Table](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Table.md) |
+| Interactive | [Tabs](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Tabs.md), [Button](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Button.md), [Choice](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Choice.md), [Faq](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Faq.md) |
+| Rich content | [Markdown](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Markdown.md), [CodeBlock](https://github.com/newtonapple/pi-openui/blob/main/docs/components/CodeBlock.md), [Image](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Image.md) |
+| Charts | [BarChart](https://github.com/newtonapple/pi-openui/blob/main/docs/components/BarChart.md), [LineChart](https://github.com/newtonapple/pi-openui/blob/main/docs/components/LineChart.md), [AreaChart](https://github.com/newtonapple/pi-openui/blob/main/docs/components/AreaChart.md), [PieChart](https://github.com/newtonapple/pi-openui/blob/main/docs/components/PieChart.md), [RadarChart](https://github.com/newtonapple/pi-openui/blob/main/docs/components/RadarChart.md) |
+| Diagrams and maps | [Dag](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Dag.md), [Erd](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Erd.md), [InfraMap](https://github.com/newtonapple/pi-openui/blob/main/docs/components/InfraMap.md), [SequenceDiagram](https://github.com/newtonapple/pi-openui/blob/main/docs/components/SequenceDiagram.md), [GeoMap](https://github.com/newtonapple/pi-openui/blob/main/docs/components/GeoMap.md) |
+
+[Tooltip](https://github.com/newtonapple/pi-openui/blob/main/docs/components/Tooltip.md) attaches to Dag, Erd, InfraMap, SequenceDiagram, Table, Metric, BarChart,
+LineChart, AreaChart, PieChart, RadarChart, GeoMap and Image.
+
+## How it works
+
+```
+OpenUI Lang --parse--> typed tree --render--> blocks (rows of cells + click targets) --> pi-tui lines
+                                                     ^                                       |
+                                       interaction logic: hit test, keys, panning   <-- mouse and keys
+```
+
+- `src/lang/` parses and validates OpenUI Lang with one table of component signatures. The same table writes the reference the
+  agent reads and the docs pages you see here.
+- `src/blocks/` turns each component into a grid of styled cells plus the places you can click.
+- `src/diagram/` is the layout and routing engine for Dag, Erd and InfraMap.
+- `src/pi/` is the pi extension: the tool, the commands, the themed component, mouse and keyboard handling, pictures.
+
+More in [docs/design.md](https://github.com/newtonapple/pi-openui/blob/main/docs/design.md).
+
+## Requirements
+
+- pi 1.4 or newer.
+- Node 22.18 or newer for the tests and scripts (they run TypeScript directly). Developed on Node 26.
+- A terminal font with the glyphs the widgets use. They were chosen from, and are tested against, JetBrains Mono Nerd Font
+  Mono. A different font works if it has them: `PI_OPENUI_FONT=/path/to/font.ttf npm test` checks yours.
+- Pictures need a terminal that supports the Kitty graphics protocol. Other terminals get a framed placeholder.
+
+## Development
+
+Working on the code? Start pi in this folder instead of installing it: `.pi/extensions/openui.ts` loads the extension (pi asks
+once whether to trust the folder). To load it from somewhere else for one session:
+
+```sh
+pi -e /path/to/pi-openui/.pi/extensions/openui.ts
+```
+
+After you change the code, run `/reload` in pi. The rest:
+
+```sh
+npm test                 # a few seconds, no network, no model calls
+npm run docs             # regenerate docs/components/ from the signature table
+npm run screenshots      # regenerate docs/screenshots/, and the two README composites (needs Python with Pillow, and the font)
+npm run gallery          # print every component to the terminal (-- --plain for no colour)
+make help                # the release process (check, version, publish, tag, push)
+```
+
+Tests are described in [docs/testing.md](https://github.com/newtonapple/pi-openui/blob/main/docs/testing.md). Releases are described in [docs/releasing.md](https://github.com/newtonapple/pi-openui/blob/main/docs/releasing.md).
+Contributors and agents working in this repository should read [AGENTS.md](https://github.com/newtonapple/pi-openui/blob/main/AGENTS.md).
+
+## Limits
+
+- Hover needs a terminal that reports mouse movement. The keyboard covers everything else.
+- Only Kitty-protocol terminals show pictures. A tooltip attaches to a whole picture, not to a spot inside it.
+- Dense graphs of 11 or more nodes can be wider than the terminal. They scroll sideways, and moving focus scrolls the node
+  into view.
+- The map uses 110m coastlines: country scale, not city scale.
+- Widgets are not saved anywhere but pi's own session. A resumed session redraws them from the tool results. Notes are not
+  saved at all.
+- A widget has size limits (100 KB of source, 100 table rows, 60 graph nodes, 30 map nodes, and so on). Over a limit the
+  agent gets an error with the number and fixes it. They keep pi fast: it draws every widget on every frame. See the
+  [list](https://github.com/newtonapple/pi-openui/blob/main/docs/components/README.md#size-limits).
+
+## License
+
+[MIT](LICENSE).

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "pi-openui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Pi extension: interactive dashboards, charts, diagrams and maps in the terminal. The agent draws with OpenUI Lang; you click, hover and pin notes.",
+  "license": "MIT",
+  "author": "David Dai",
+  "homepage": "https://github.com/newtonapple/pi-openui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/newtonapple/pi-openui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/newtonapple/pi-openui/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "coding-agent",
+    "openui",
+    "tui",
+    "terminal",
+    "dashboard",
+    "charts",
+    "diagrams",
+    "widgets",
+    "visualization"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/pi/extension.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/newtonapple/pi-openui/main/docs/screenshots/dashboard.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --import ./test/register-pi.mjs --test --test-reporter=spec test/*.test.ts",
+    "gallery": "node scripts/langgallery.ts",
+    "screenshots": "node --import ./test/register-pi.mjs scripts/shots.ts && python3 scripts/render_shots.py && python3 scripts/hero.py",
+    "docs": "node scripts/gen_docs.ts",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/blocks/braille.ts

@@ -0,0 +1,121 @@
+// A dot canvas drawn with braille characters: 2 x 4 dots per cell, square dots in a 1:2 cell.
+import { cell, EMPTY, type Cell } from "../diagram/canvas.ts";
+
+const BITS = [
+	[0x01, 0x02, 0x04, 0x40],
+	[0x08, 0x10, 0x20, 0x80],
+];
+
+export class Dots {
+	readonly cols: number;
+	readonly rows: number;
+	readonly w: number;
+	readonly h: number;
+	readonly bits: Uint8Array;
+	readonly owner: Int16Array;
+	constructor(cols: number, rows: number) {
+		this.cols = cols;
+		this.rows = rows;
+		this.w = cols * 2;
+		this.h = rows * 4;
+		this.bits = new Uint8Array(cols * rows);
+		this.owner = new Int16Array(cols * rows).fill(-1);
+	}
+	set(x: number, y: number, owner: number): void {
+		x = Math.round(x);
+		y = Math.round(y);
+		if (x < 0 || y < 0 || x >= this.w || y >= this.h) return;
+		const c = (y >> 2) * this.cols + (x >> 1);
+		this.bits[c] |= BITS[x & 1][y & 3];
+		this.owner[c] = owner;
+	}
+	line(x0: number, y0: number, x1: number, y1: number, owner: number): void {
+		x0 = Math.round(x0);
+		y0 = Math.round(y0);
+		x1 = Math.round(x1);
+		y1 = Math.round(y1);
+		const dx = Math.abs(x1 - x0);
+		const dy = -Math.abs(y1 - y0);
+		const sx = x0 < x1 ? 1 : -1;
+		const sy = y0 < y1 ? 1 : -1;
+		let err = dx + dy;
+		for (let guard = 0; guard < 100000; guard++) {
+			this.set(x0, y0, owner);
+			if (x0 === x1 && y0 === y1) break;
+			const e2 = 2 * err;
+			if (e2 >= dy) {
+				err += dy;
+				x0 += sx;
+			}
+			if (e2 <= dx) {
+				err += dx;
+				y0 += sy;
+			}
+		}
+	}
+	rows2cells(roleFor: (owner: number) => string): Cell[][] {
+		const out: Cell[][] = [];
+		for (let r = 0; r < this.rows; r++) {
+			const row: Cell[] = [];
+			for (let c = 0; c < this.cols; c++) {
+				const b = this.bits[r * this.cols + c];
+				row.push(b ? cell(String.fromCharCode(0x2800 + b), roleFor(this.owner[r * this.cols + c])) : EMPTY);
+			}
+			out.push(row);
+		}
+		return out;
+	}
+}
+
+export function niceNum(x: number, round: boolean): number {
+	if (x <= 0) return 1;
+	const exp = Math.floor(Math.log10(x));
+	const f = x / 10 ** exp;
+	const nf = round ? (f < 1.5 ? 1 : f < 3 ? 2 : f < 7 ? 5 : 10) : f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10;
+	return nf * 10 ** exp;
+}
+
+export function fmtNum(v: number): string {
+	if (!Number.isFinite(v)) return "?";
+	const a = Math.abs(v);
+	if (a >= 1e6) return `${+(v / 1e6).toFixed(1)}M`;
+	if (a >= 1e4) return `${+(v / 1e3).toFixed(1)}k`;
+	if (Number.isInteger(v)) return String(v);
+	return String(+v.toFixed(a < 1 ? 3 : a < 100 ? 2 : 1));
+}
+
+/** monotone cubic interpolation (no overshoot) evaluated at x */
+export function monotone(xs: number[], ys: number[]): (x: number) => number {
+	const n = xs.length;
+	if (n === 1) return () => ys[0];
+	const d: number[] = [];
+	const m: number[] = new Array(n).fill(0);
+	for (let i = 0; i < n - 1; i++) d.push((ys[i + 1] - ys[i]) / (xs[i + 1] - xs[i] || 1));
+	m[0] = d[0];
+	m[n - 1] = d[n - 2];
+	for (let i = 1; i < n - 1; i++) m[i] = d[i - 1] * d[i] <= 0 ? 0 : (d[i - 1] + d[i]) / 2;
+	for (let i = 0; i < n - 1; i++) {
+		if (d[i] === 0) {
+			m[i] = 0;
+			m[i + 1] = 0;
+			continue;
+		}
+		const a = m[i] / d[i];
+		const b = m[i + 1] / d[i];
+		const s = a * a + b * b;
+		if (s > 9) {
+			const t = 3 / Math.sqrt(s);
+			m[i] = t * a * d[i];
+			m[i + 1] = t * b * d[i];
+		}
+	}
+	return (x: number) => {
+		let i = 0;
+		while (i < n - 2 && x > xs[i + 1]) i++;
+		const h = xs[i + 1] - xs[i] || 1;
+		const t = Math.min(1, Math.max(0, (x - xs[i]) / h));
+		const t2 = t * t;
+		const t3 = t2 * t;
+		return (2 * t3 - 3 * t2 + 1) * ys[i] + (t3 - 2 * t2 + t) * h * m[i] + (-2 * t3 + 3 * t2) * ys[i + 1] + (t3 - t2) * h * m[i + 1];
+	};
+}

package/src/blocks/bubble.ts

@@ -0,0 +1,30 @@
+// The hover bubble: a one-line tooltip drawn over the cells next to the element, inside the widget's own rows so
+// the transcript does not jump when it appears.
+import { cell, EMPTY, textWidth, truncateText, type Cell } from "../diagram/canvas.ts";
+import { BADGE } from "./core.ts";
+import type { Target } from "./types.ts";
+import { textCells } from "./util.ts";
+
+export function drawBubble(rows: Cell[][], width: number, t: Target): void {
+	const hint = t.tip?.hint?.replace(/\s+/g, " ").trim();
+	if (!hint || !rows.length) return;
+	const text = truncateText(hint, Math.max(8, Math.min(76, width - 5)));
+	const cells: Cell[] = [cell(" ", "tip.bubble"), cell(BADGE, `tip.bubble.${t.tip?.tone ?? "info"}`), cell(" ", "tip.bubble"), ...textCells(text, "tip.bubble"), cell(" ", "tip.bubble")];
+	const w = Math.min(width, 4 + textWidth(text) + 1);
+	const r = t.rect;
+	// above the element if there is a row there, else below it, else over its own row to the right
+	let y = r.y - 1;
+	if (y < 0) y = r.y + r.h;
+	let x = Math.max(0, Math.min(r.x, width - w));
+	if (y >= rows.length) {
+		y = Math.min(r.y, rows.length - 1);
+		x = Math.max(0, Math.min(r.x + r.w + 1, width - w));
+	}
+	const row = rows[y];
+	if (!row) return;
+	// do not cut a wide character in half at either end of the bubble
+	if (row[x]?.ch === "") row[x - 1] = EMPTY;
+	const end = x + w;
+	if (row[end]?.ch === "") row[end] = EMPTY;
+	for (let i = 0; i < w && x + i < row.length; i++) row[x + i] = cells[i] ?? cell(" ", "tip.bubble");
+}